home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat3 / Tk / getcolor.z / getcolor
Text File  |  1998-10-30  |  12KB  |  199 lines
  1.  
  2.  
  3.  
  4. TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr((((3333TTTTkkkk))))                                              TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr((((3333TTTTkkkk))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      Tk_GetColor, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColor - maintain
  10.      database of colors
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>>
  14.  
  15.      XColor *
  16.      TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr(_i_n_t_e_r_p, _t_k_w_i_n, _n_a_m_e_I_d))))
  17.  
  18.      XColor *                                                                 |
  19.      TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrrBBBByyyyVVVVaaaalllluuuueeee(_t_k_w_i_n, _p_r_e_f_P_t_r))))                                       |
  20.  
  21.      char *
  22.      TTTTkkkk____NNNNaaaammmmeeeeOOOOffffCCCCoooolllloooorrrr((((_c_o_l_o_r_P_t_r))))
  23.  
  24.      GC                                                                       |
  25.      TTTTkkkk____GGGGCCCCFFFFoooorrrrCCCCoooolllloooorrrr(_c_o_l_o_r_P_t_r, _d_r_a_w_a_b_l_e)                                        |
  26.  
  27.      TTTTkkkk____FFFFrrrreeeeeeeeCCCCoooolllloooorrrr((((_c_o_l_o_r_P_t_r))))
  28.  
  29. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  30.      Tcl_Interp   *_i_n_t_e_r_p     (in)      Interpreter to use for error
  31.                                         reporting.
  32.  
  33.      Tk_Window    _t_k_w_i_n       (in)      Token for window in which color will
  34.                                         be used.
  35.  
  36.      Tk_Uid       _n_a_m_e_I_d      (in)      Textual description of desired color.
  37.  
  38.      XColor       *_p_r_e_f_P_t_r    (in)      Indicates red, green, and blue
  39.                                         intensities of desired color.
  40.  
  41.      XColor       *_c_o_l_o_r_P_t_r   (in)      Pointer to X color information.  Must
  42.                                         have been allocated by previous call
  43.                                         to TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr or TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrrBBBByyyyVVVVaaaalllluuuueeee,
  44.                                         except when passed to TTTTkkkk____NNNNaaaammmmeeeeOOOOffffCCCCoooolllloooorrrr.
  45.  
  46.      Drawable     _d_r_a_w_a_b_l_e    (in)      Drawable in which the result graphics |
  47.                                         context will be used.  Must have same |
  48.                                         screen and depth as the window for    |
  49.                                         which the color was allocated.
  50.  
  51.  
  52. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  53.      The TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr and TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrrBBBByyyyVVVVaaaalllluuuueeee procedures locate pixel values
  54.      that may be used to render particular colors in the window given by
  55.      _t_k_w_i_n.  In TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr the desired color is specified with a Tk_Uid
  56.      (_n_a_m_e_I_d), which may have any of the following forms:
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr((((3333TTTTkkkk))))                                              TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr((((3333TTTTkkkk))))
  71.  
  72.  
  73.  
  74.      _c_o_l_o_r_n_a_m_e           Any of the valid textual names for a color defined in
  75.                          the server's color database file, such as rrrreeeedddd or
  76.                          PPPPeeeeaaaacccchhhhPPPPuuuuffffffff.
  77.  
  78.      ####_R_G_B
  79.  
  80.      ####_R_R_G_G_B_B
  81.  
  82.      ####_R_R_R_G_G_G_B_B_B
  83.  
  84.      ####_R_R_R_R_G_G_G_G_B_B_B_B       A numeric specification of the red, green, and blue
  85.                          intensities to use to display the color.  Each _R, _G,
  86.                          or _B represents a single hexadecimal digit.  The four
  87.                          forms permit colors to be specified with 4-bit, 8-
  88.                          bit, 12-bit or 16-bit values.  When fewer than 16
  89.                          bits are provided for each color, they represent the
  90.                          most significant bits of the color.  For example,
  91.                          #3a7 is the same as #3000a0007000.
  92.  
  93.      In TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrrBBBByyyyVVVVaaaalllluuuueeee, the desired color is indicated with the _r_e_d,
  94.      _g_r_e_e_n, and _b_l_u_e fields of the structure pointed to by _c_o_l_o_r_P_t_r.
  95.  
  96.      If TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr or TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrrBBBByyyyVVVVaaaalllluuuueeee is successful in allocating the
  97.      desired color, then it returns a pointer to an XColor structure;  the
  98.      structure indicates the exact intensities of the allocated color (which
  99.      may differ slightly from those requested, depending on the limitations of
  100.      the screen) and a pixel value that may be used to draw in the color.  If |
  101.      the colormap for _t_k_w_i_n is full, TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr and TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrrBBBByyyyVVVVaaaalllluuuueeee will  |
  102.      use the closest existing color in the colormap.  If TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr          |
  103.      encounters an error while allocating the color (such as an unknown color |
  104.      name) then NULL is returned and an error message is stored in _i_n_t_e_r_p-    |
  105.      >_r_e_s_u_l_t; TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrrBBBByyyyVVVVaaaalllluuuueeee never returns an error.
  106.  
  107.      TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr and TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrrBBBByyyyVVVVaaaalllluuuueeee maintain a database of all the colors
  108.      currently in use.  If the same _n_a_m_e_I_d is requested multiple times from
  109.      TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr (e.g. by different windows), or if the same intensities are
  110.      requested multiple times from TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrrBBBByyyyVVVVaaaalllluuuueeee, then existing pixel
  111.      values will be re-used.  Re-using an existing pixel avoids any
  112.      interaction with the X server, which makes the allocation much more
  113.      efficient.  For this reason, you should generally use TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr or
  114.      TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrrBBBByyyyVVVVaaaalllluuuueeee instead of Xlib procedures like XXXXAAAAllllllllooooccccCCCCoooolllloooorrrr,
  115.      XXXXAAAAllllllllooooccccNNNNaaaammmmeeeeddddCCCCoooolllloooorrrr, or XXXXPPPPaaaarrrrsssseeeeCCCCoooolllloooorrrr.
  116.  
  117.      Since different calls to TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr or TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrrBBBByyyyVVVVaaaalllluuuueeee may return the
  118.      same shared pixel value, callers should never change the color of a pixel
  119.      returned by the procedures.  If you need to change a color value
  120.      dynamically, you should use XXXXAAAAllllllllooooccccCCCCoooolllloooorrrrCCCCeeeellllllllssss to allocate the pixel value
  121.      for the color.
  122.  
  123.      The procedure TTTTkkkk____NNNNaaaammmmeeeeOOOOffffCCCCoooolllloooorrrr is roughly the inverse of TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr.  If
  124.      its _c_o_l_o_r_P_t_r argument was created by TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr, then the return value
  125.      is the _n_a_m_e_I_d string that was passed to TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr to create the color.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr((((3333TTTTkkkk))))                                              TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr((((3333TTTTkkkk))))
  137.  
  138.  
  139.  
  140.      If _c_o_l_o_r_P_t_r was created by a call to TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrrBBBByyyyVVVVaaaalllluuuueeee, or by any other
  141.      mechanism, then the return value is a string that could be passed to
  142.      TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr to return the same color.  Note:  the string returned by
  143.      TTTTkkkk____NNNNaaaammmmeeeeOOOOffffCCCCoooolllloooorrrr is only guaranteed to persist until the next call to
  144.      TTTTkkkk____NNNNaaaammmmeeeeOOOOffffCCCCoooolllloooorrrr.
  145.  
  146.      TTTTkkkk____GGGGCCCCFFFFoooorrrrCCCCoooolllloooorrrr returns a graphics context whose FFFFoooorrrreeeeggggrrrroooouuuunnnndddd field is the   |
  147.      pixel allocated for _c_o_l_o_r_P_t_r and whose other fields all have default     |
  148.      values.  This provides an easy way to do basic drawing with a color.  The|
  149.      graphics context is cached with the color and will exist only as long as |
  150.      _c_o_l_o_r_P_t_r exists;  it is freed when the last reference to _c_o_l_o_r_P_t_r is     |
  151.      freed by calling TTTTkkkk____FFFFrrrreeeeeeeeCCCCoooolllloooorrrr.
  152.  
  153.      When a pixel value returned by TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr or TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrrBBBByyyyVVVVaaaalllluuuueeee is no
  154.      longer needed, TTTTkkkk____FFFFrrrreeeeeeeeCCCCoooolllloooorrrr should be called to release the color.  There
  155.      should be exactly one call to TTTTkkkk____FFFFrrrreeeeeeeeCCCCoooolllloooorrrr for each call to TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr
  156.      or TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrrBBBByyyyVVVVaaaalllluuuueeee.  When a pixel value is no longer in use anywhere
  157.      (i.e. it has been freed as many times as it has been gotten) TTTTkkkk____FFFFrrrreeeeeeeeCCCCoooolllloooorrrr
  158.      will release it to the X server and delete it from the database.
  159.  
  160.  
  161. KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  162.      color, intensity, pixel value
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.